home *** CD-ROM | disk | FTP | other *** search
/ ShareWare OnLine 2 / ShareWare OnLine Volume 2 (CMS Software)(1993).iso / database / mulco303.zip / MULTICOL.DOC < prev    next >
Text File  |  1993-03-20  |  17KB  |  338 lines
  1. MULTICOL.DOC
  2. 03/20/93
  3.  
  4. The MULTICOL.EXE program creates multi-columned listings from a text file.  This
  5. listing typically goes to a disk file but it can be routed to a printer or to
  6. the screen instead.  Titles, column headers, and footers are supported.  To a
  7. limited extent, you can use MULTICOL to add headers and footers to regular text
  8. documents as well.
  9.  
  10. The program also supports the formatted output of ASCII-delimited and dBase
  11. files.
  12.  
  13. You can also specify that columns of data be totalled as well as having tally
  14. counts generated.
  15.  
  16.  
  17. Stored control file:
  18.  
  19. The routine allows for a number of parameters, most of which can be very long.
  20. To avoid keying all of these in each time, a control file is provided for.  The
  21. control file is designated with the "/Ccontrol_file" parameter and consists
  22. of regular MULTICOL parameters. Every parameter except the /Ccontrol_file
  23. parameter itself is allowed.
  24.  
  25. The control file provides several benefits for you.  (a) It makes it easier to
  26. enter the same parameters multiple times.  (b) It avoids too-long lines in DOS
  27. (DOS can't handle lines above about 120 characters in length).  (c) It allows
  28. you to store default printer characteristics (one or more sets of them actually)
  29. and bring them in easily.  (d) It allows you to maintain default formats for
  30. your output.
  31.  
  32. The format for the control statement file is essentially free-form.  Empty lines
  33. and lines which begin with a semi-colon or colon are ignored.  Typically,
  34. parameters begin in column 1 and only one parameter is provided on each line but
  35. this is optional.  For example:
  36.  
  37.         ; Sample control file for MULTICOL program
  38.         ; This one is for printing wide files (132-columns)
  39.         /DELIM=" │ "
  40.         /WIDTH=132
  41.         ; This is the setup string used to set a LaserJet to compressed
  42.         ; portrait mode.
  43.         /SETUP="/027(s16.66H"
  44.         ; Don't want to leave the printer in that mode when you leave.
  45.         /RESET="/027E"
  46.         ; The printer already has pre-defined page lengths so don't
  47.         ; put in page ejects.
  48.         /-EJECT
  49.  
  50. You can override any of the parameters in the control file from the command line
  51. when you invoke MULTICOL.  (Exception:  If your control card file includes input
  52. and/or output file name specifications, these cannot be overridden from the
  53. command line.)
  54.  
  55.  
  56. For ASCII-delimited and dBase input files, you can use MULTICOL to present a
  57. reasonably formatted listing of variables.  A definition file (deffile) is
  58. either read of created for you.  A deffile is used to figure out the
  59. characteristics for each field and also to set certain file characteristics.
  60. The definition file can be created with any text editor.  The definition file
  61. consists of several records with the following fields separated by spaces.
  62. Except for the record type indicator (which must begin in column 1), all other
  63. fields can be placed in any columns:
  64.  
  65.         (1) record type (see below)
  66.         (2) length of field on input
  67.         (3) number of decimal places for numeric data (if you don't know,
  68.             put a "?" here; for non-numeric data, a "0" is fine) on output
  69.         (4) length of field on output
  70.  
  71. Any characters after the field length are treated as comment fields.  You would
  72. typically use this to enter the field name or column position or any other
  73. information of use to you.
  74.  
  75. The data record types accepted by MULTICOL are as follows:
  76.  
  77.         type C = character data
  78.              N = numeric
  79.              L = logical (T or F)
  80.              D = date (in yyyymmdd format)
  81.  
  82. Other records accepted in the field definition file are as follows:
  83.  
  84.         type ; = comment (anything after semi-colon is ignored)
  85.              X = lines to ignore; specify "X=string" and any records
  86.                  which begin with the "string" characters will be ignored;
  87.                  defaults to X="_
  88.              Z = delimiter between fields; defaults to Z=,
  89.  
  90. The data fields (types C, N, L, and D) should be in the order the fields are
  91. found in the source file.
  92.  
  93. For dBase files, a deffile will automatically be created for you unless you
  94. specify /USEDEF.  In that case, the routine will read the deffile and act
  95. appropriately.  This is necessary if you want fields expanded or ignored.
  96.  
  97. You can also use the /PRINT specification to select which files you want
  98. printed.
  99.  
  100. For adding headers and footers to regular text files, make sure you specify
  101. /COLUMNS=1.  The system starts a new page when it runs into lines with page
  102. eject characters or when it hits the number of lines specified in the /LINE=n
  103. parameter.  (The page eject part is only true if /-WRAP is in effect.)
  104.  
  105.  
  106. Syntax:
  107.  
  108.     MULTICOL infile outfile [ /OVERWRITE | /-OVERWRITE | /OVERASK ]
  109.       [ /DELIM="string" ]
  110.       [ /LINES=n ] [ /WIDTH=n ] [ /EJECT | /-EJECT ]
  111.       [ /COLUMNS=n ] [ /WRAP | /-WRAP [ /INDENT=n ] | /REFLOW ]
  112.       [ /Ccontrol_file ] [ /SETUP="string" ] [ /RESET="string" ]
  113.       [ /{ TITLE | HEADER | FOOTER }[ R | C | L ][ 1 to 5]="text" ]
  114.       [ /{ TITLE | HEADER | FOOTER }{ T | B }="string" ]
  115.       [ /FROM ASCII | /FROM ASCII=char | /FROM DBF ] [ /DEF=deffile ]
  116.       [ /SKIP | /MISSING | /ABORT ] [ /GAP=n ] [ /USEDEF ] [ /TALLY ]
  117.       [ /SUM={ col_spec | var_spec } ] [ /BREAK={ col_spec | var_spec } ]
  118.       [ /PRINT={ col_spec | var_spec } ] [ /? ]
  119.  
  120. where:
  121.  
  122. "infile" is the name of the ASCII text file that you want reformatted into a
  123. multicolumn file.
  124.  
  125. "outfile" is the name of the ASCII text file that you want to create.  "infile"
  126. and "outfile" cannot be the same.  While "outfile" is typically a file name, you
  127. can specify devices like "PRN:" or "SCRN:" if you want to.
  128.  
  129. "/OVERWRITE" says to write over the outfile if it already exists.
  130.  
  131. "/-OVERWRITE" says to abort if the outfile exists already.
  132.  
  133. "/OVERASK" says to prompt if the outfile exists already.  This is the default.
  134.  
  135. "/DELIM="string"" indicates the character string that should be used to separate
  136. columns.  Note that the string itself must appear within quotation marks.  By
  137. default, the string is " | ".
  138.  
  139. "/LINES=n" indicates how many physical lines can fit on your printed page.
  140. Defaults to /LINES=60.
  141.  
  142. "/WIDTH=n" indicates how many physical characters can fit on your printed page.
  143. Defaults to /WIDTH=80.  Typically, if you are in compressed mode, the value is
  144. /WIDTH=132.
  145.  
  146. "/EJECT" says to add a page eject after the maximum lines-per-page (/LINES=n)
  147. setting.  This is not recommended if you're using a printer with a defined page
  148. size that is the the same or smaller than the /LINES=n setting.  If you're using
  149. something like a LaserJet, setting /EJECT will typically result in blank pages
  150. being generated after each full page.  The default is "/-EJECT".
  151.  
  152. "/-EJECT" is the opposite of "/EJECT".  This is the default.
  153.  
  154.  
  155. "/COLUMNS=n" indicates how many text columns you want to appear.  The value can
  156. be as low as one (useful if you're just doing reformatting of paragraphs).
  157. There's no maximum value but anything above 7 or so starts looking worthless.
  158. The default value is /COLUMNS=2.
  159.  
  160. The combination of the /COLUMNS=n, /DELIM="string", and /WIDTH=n tells the
  161. program how wide each physical column is.  For example, using the defaults of
  162. /COLUMNS=2, /DELIM=" | ", and /WIDTH=80, each text column is a maximum of 38
  163. characters.  (Width - (Size of Delimiter * (Number of columns - 1), all divided
  164. by 2.  INT((80-(3*1))/2) is 38.) The routine tells you what column size it
  165. picked; if you don't like the result, adjust some of your other parameters and
  166. try it again.
  167.  
  168. "/WRAP", "/-WRAP", and "/REFLOW" tells the program what you want it to do with
  169. text that exceeds the width of each physical column.  The default is /-WRAP.
  170. Each is explained separately below:
  171.  
  172. "/-WRAP" indicates that long lines are to be truncated and the excess characters
  173. are lost.  This is the default.
  174.  
  175. "/WRAP" says the line is to be parsed into words and any word(s) that doesn't
  176. fit on the original line spills over on successive line(s).  The spillover lines
  177. are indented by the value of "/INDENT=n".  By default, the secondary lines are
  178. indented by 2 spaces.
  179.  
  180. "/REFLOW" is the most sophisticated of the options.  /REFLOW will treat most of
  181. the text as paragraphs are readjust the length of the entire paragraph.  The
  182. reflowing stops whenever a new paragraph is detected.  The routine considers a
  183. new paragraph to start whenever the succeeding line is either blank or it starts
  184. with a space.  Unlike with the other options, you can actually end up with fewer
  185. lines in your output file than you had in your input file using /REFLOW.  This
  186. only happens of course if the source lines were generally shorter than the
  187. computer text column width.
  188.  
  189. "/Ccontrol_file" specifies an external text file that contains control
  190. statements.  See the discussion above about control files.
  191.  
  192. "/SETUP="string"" specifies the initialization string to put at the beginning of
  193. the file.  This is typically used to make sure your printer has the proper
  194. orientation (landscape vs portrait), characters per inch (cpi), and lines per
  195. inch (lpi) settings before printing.  The setup string itself must appear in
  196. quotation marks.  Use "/027" for the Escape character and any other ASCII code
  197. can be entered with "/" followed by its 3-digit value (e.g.  "/032" is a space).
  198. You have to know your own setup strings.  Borland's documentation provides some
  199. very useful tables for this sort of thing.  For an HP LaserJet, the setups I use
  200. all of the time are:
  201.  
  202.         Orientation     PageLen RMargin String
  203.  
  204.         Portrait        60      80      /027E
  205.         Portrait        60      132     /027(s16.66H
  206.         Landscape       45      106     /027&l10
  207.         Landscape       45      176     /027&l10/027(s16.66H
  208.         Landscape       66      106     /027&l1o5.45C
  209.         Landscape       66      176     /027&l1o5.45C/027(s16.66H
  210.  
  211.  
  212. "/RESET="string"" specifies the string to send after your file is done.  This
  213. typically resets the printer to its system default setting so you won't get
  214. stuck in landscape mode forever.  The setup string itself must appear in
  215. quotation marks.  Use "/027" for the Escape character.  For an HP LaserJet, the
  216. following resets the printer to its factory settings:
  217.  
  218.         /027E
  219.  
  220. "/{ TITLE | HEADER | FOOTER } [ R | C | L ] [ 1 to 5 ]="text"" allows you to
  221. specify up to 5 lines each for the report's TITLE (at the top of each page),
  222. HEADER (at the top of each column), and FOOTER (at the bottom of each page).
  223. You can specify positioning as well:
  224.  
  225.         R = right-justify the text
  226.         C = center the text (this is the default for /TITLE and /HEADER)
  227.         L = left-justify the text (this is the default for /FOOTER)
  228.  
  229. If no line number is specified, line 1 is presumed.  If a line number is
  230. specified, all lines before that number are presumed to contain something and
  231. will be blank filled if you don't provide anything.  If, for example, you
  232. specify "/TITLER3="Hi!"", without specifying any other titles, then you'll get
  233. blank lines for /TITLE1 and /TITLE2, but you won't get any /TITLE4 or /TITLE5.
  234.  
  235. The text itself can contain one of six imbedded string-replacement codes:
  236.  
  237.         ^B will be replaced by the page number
  238.         ^D will be replaced by today's date (in mm/dd/yy form)
  239.         ^T will be replaced by today's time (in hh:mm form)
  240.         ^N will be replaced by the input file's name
  241.         ^A will be replaced by the input file's creation date (mm/dd/yy form)
  242.         ^I will be replaced by the input file's creation time (hh:mm form)
  243.  
  244. "/{TITLE | HEADER | FOOTER }{ T | B }="string"" allows you to specify a
  245. repeating string to be placed either on top of or on the bottom of your titles,
  246. headers, and footers.  The string, typically consisting of just a few
  247. characters, is repeated by the routine until it fills up the available space.
  248. For example, "/TITLET=" -"" would add the following line at the top of the
  249. report:
  250.  
  251.  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  252.  
  253. This option is typically used to (a) insure that there are blank lines before
  254. footer lines and (b) to have demarcations between sections.
  255.  
  256. "/FROM ASCII" says that the input file is ASCII-delimited (with quotes around
  257. strings and commas between fields).  Alternatively, you can specify that the
  258. file is "/FROM ASCII=char" and the "char" character will be used as a delimiter
  259. between fields instead of a comma.  The routine will require that a deffile
  260. (/DEF=defile) be specified with the definition of fields.
  261.  
  262. "/FROM DBF" specifies that the input file is a dBase file.  If the file
  263. extension is .DBF, the routine will presume this.  The routine uses dBase's
  264. default field lengths unless /USEDEF is specified along with /DEF=deffile.
  265.  
  266. "/DEF=deffile" provides the name of the definition file for ASCII-delimited and
  267. some dBase input files.  A description of the definition file was given
  268. previously.
  269.  
  270.  
  271. "/SKIP" says to skip ASCII-delimited records with bad data values; otherwise the
  272. routine aborts when it runs into any.  /SKIP, /MISSING, and /ABORT are mutually
  273. exclusive.
  274.  
  275. "/MISSING" says to presume any missing fields in an ASCII-delimited record
  276. should be filled in with blanks (for character fields) and 0 for numeric fields.
  277. Incomplete records are written out (unlike in /SKIP).  /SKIP, /MISSING, and
  278. /ABORT are mutually exclusive.
  279.  
  280. "/ABORT" says to abort when you run into bad records.  This is typically the
  281. default.  /SKIP, /MISSING, and /ABORT are mutually exclusive.
  282.  
  283. "/GAP=n" is used when printing ASCII-delimited or dBase files.  It tells the
  284. program how many spaces to print between each variable.  The default is /GAP=2.
  285.  
  286. "/USEDEF" is specified for dBase input files if you want MULTICOL to read an
  287. existing field-definition file.  Since dBase files contain all of the field
  288. information in the data base itself, MULTICOL will normally pick up all field
  289. information from there and simply ignore any field-definition file.
  290.  
  291. "/TALLY" says to present a count of items.  If a /BREAK specification is
  292. provided, there will be a tally for each break as well as for the grand total.
  293.  
  294.  
  295. "/SUM={ col_spec | var_spec }" says to summarize (add) all values in particular
  296. columns.  If ASCII-delimited or dBase input is used, you can specify variables
  297. to be added.  If a /BREAK specification is provided, there will be subtotals at
  298. each break as well as grand total.
  299.  
  300. The "col_spec | var_spec" portion expands to "{ Cx[-x] | Vx[-x] } [, {Cx[-x] |
  301. Vx[-x] } ]..." where "x" is the column or variable number, "-" indicates a
  302. range, and "C" means column whereas "V" means variable.  If you have an
  303. ASCII-delimited file and you want the values of the first three variables
  304. summarized, you'd say "/SUM=C1-3".  If you want variables 2, and 4 through 6
  305. summarized, you'd say "/SUM=C2,C4-6".  If you want the values in columns 10
  306. through 20 summarized, you'd say "/SUM=C10-20".  Note that for column
  307. specifications, you have to request the output columns, not input columns.
  308.  
  309. "/BREAK={ col_spec | var_spec }" says to present tally, total, or blank lines
  310. based on the values in certain columns or variables.  For example, if you had an
  311. alphabetical listing and you wanted to, you could break up the listing by the
  312. first letter of the last name.  A break is generated whenever there is a change
  313. in any character in the column or variable range specified.  The
  314. "col_spec | var_spec" specification is identical to the /SUM specification.
  315.  
  316. "/PRINT={ col_spec | var_spec }" says to print only some of the fields.  For
  317. example, if you have a dBase file with 10 variables and you only want some of
  318. them to print out, you can say "/PRINT=V1-3,V6,V8" or something like that.  Note
  319. that the /PRINT specification works in conjunction with any 0-length output
  320. specifications in the deffile.
  321.  
  322. "/?" or "/HELP" or "HELP" gives you syntactical help.
  323.  
  324.  
  325. This program was written by Bruce Guthrie of Wayne Software.  It is free for use
  326. provided relevant documentation is kept with the program, no changes are made to
  327. the program or documentation, and it is not bundled with commercial programs or
  328. charged for separately.  People who need to bundle it in for-sale packages must
  329. pay a $50 registration fee to "Wayne Software" at the following address.
  330. Comments and suggestions can also be sent to:
  331.  
  332.                 Bruce Guthrie
  333.                 Wayne Software
  334.                 113 Sheffield St.
  335.                 Silver Spring, MD 20910
  336.  
  337.                 fax: (301) 588-8986
  338.